<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>A window</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="Windows API, Winapi, Win32, C, a window">
<meta name="description" content="In this part of the Winapi tutorial, we 
will create a simple window.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container2">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content2">


<a href="/" title="Home">Home</a>&nbsp;
<a href="..">Contents</a>


<h1>A Window</h1>


<p>
Everything is a window in Windows. At least from the programmer's point of view.
A main window, a button a static text even an icon. All are windows. A static 
text is only a special kind of a window. So is the desktop area.
</p>

<div class="big_hor">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* big_horizontal */
google_ad_slot = "2904953388";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>


<h2>WinMain function</h2>

<p>
Every Windows application must have at least two functions. The <b>WinMain</b> 
function and the <b>window procedure</b>. The WinMain function is the entry 
point to a Windows application. 
</p>

<p>
The wWinMain function initializes the application, shows the application window 
on the screen and enters the main loop.
</p>

<pre class="explanation">
int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    PWSTR pCmdLine, int nCmdShow);
</pre>

<p>
The <code>hInstance</code> is a handle of an instance. It is a 32-bit number identifying 
the instance of our program within the OS environment. This number is given 
by Windows, when the program starts executing. The <code>hPrevInstance</code> 
parameter is always NULL. It is a legacy from the 16-bit Windows. Windows programs 
can still be started from the command line. The parameters given are stored 
in <code>pCmdLine</code>. The <code>nCmdShow</code> value specifies, how the 
window will be displayed. Minimized, maximized or hidden.
</p>

<p>
The wWinMain function terminates, when it receives the 
<code>WM_QUIT</code> message. 
</p>


<h2>Registering a window</h2>

<p>
Before we can create a window, we must <b>register</b> it within the Windows. 
All windows must be registered. Later on we will see, that we do not register 
a window, when we create a button, static text etc. This is because these 
controls are predefined. They have already been registered. Programming in 
Winapi &amp; C means working with structures a lot. To register a window, 
we must create and fill an <code>WNDCLASS</code> structure. We set the window 
style, extra allocation bytes, window class name, handle of the program 
instance, background brush, optional menu name, window procedure, handle of 
the cursor and icon. Finally, we call the <code>RegisterClass()</code> function.
</p>


<h2>Creating a window</h2>

<p>
The window is created by calling the <code>CreateWindow()</code> function.
</p>
                           
<pre class="explanation">
HWND CreateWindow(LPCTSTR lpClassName, LPCTSTR lpWindowName, DWORD dwStyle, 
  int x, int y, int nWidth, int nHeight, HWND hWndParent, HMENU hMenu, 
  HINSTANCE hInstance, LPVOID lpParam);
</pre>

<p>
The <code>lpClassName</code> uniquely identifies the window. It is the name, 
under we registered the window. The <code>lpWindowName</code> is a window name. 
Its effect depends on the context. It can be title of the window in parent 
windows or a label in child windows like button or static text. Windows 
can be created using several styles. For this, we have the <code>dwStyle</code> 
parameter. The <code>x</code>, <code>y</code> specify the initial horizontal 
and vertical position of the window. The <code>nWidth</code> and 
<code>nHeight</code> specify the window width and height. The 
<code>hWndParent</code> is a handle to the parent window. 
For windows that do not have parents, we use NULL. For a parent window the
<code>hMenu</code> is an optional handle to the menu, for a child window, it is a 
control identifier. The <code>hInstance</code> is a handle to the program instance. 
The <code>lpParam</code> is the last parameter, it is an optional value passed to 
the window during the WM_CREATE message. The <code>CreateWindow()</code> 
function returns a handle to the newly created window.
</p>

<!-- TranslateMessage(Msg);  
 {Translate any WM_KEYDOWN keyboard Msg 
  to a WM_CHAR message} -->


<h2>Messages</h2>

<p>
The WinMain function creates a <b>message loop</b>. It is an endless cycle 
which runs during the life of the application. Message loop is a programming 
construct that waits for and dispatches events or messages in a program. 
Windows communicate using messages. A <b>message</b> is an integer value 
that identifies a specific event. May it be a button click, resizing of the 
window or closing of an application. There can be multiple messages created 
in one moment. The messages cannot be processed all at the same time. Therefore 
there is a <b>message queue</b>. The message enters the message queue and waits 
until it is processed. The <code>GetMessage()</code> function retrieves the message 
from the message queue. The <code>DispatchMessage()</code> function dispatches a 
message to a window procedure. If the application obtains character input, 
we include the <code>TranslateMessage()</code> function in the loop.
</p>


<h2>Window procedure</h2>

<pre class="explanation">
LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam);
</pre>

<p>
Every window must have a window procedure. It is a function that receives messages.
The <code>hwnd</code> is a handle to the window that is going to receive the message. 
The <code>uMsg</code> is the message. The <code>wParam</code> and 
<code>lParam</code> parameters provide additional message information. The values
of these parameters depend on the messege type. The messages come from the 
user or from the operating system. We react to a message or 
we call the default window procedure to provide default processing. 
Most messages are sent to the default window procedure.
The default window procedure is called <code>DefWindowProc()</code>. It is 
called with the same parameters as the normal window procedure.
</p>


<h2>A simple window</h2>

<p>
In the following example, we will show an elementary skeleton of a 
Windows application. 
</p>

<pre class="code">
#include &lt;windows.h&gt;

LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM);

int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    PWSTR pCmdLine, int nCmdShow)
{
  MSG  msg;    
  HWND hwnd;
  WNDCLASSW wc;
	
  wc.style         = CS_HREDRAW | CS_VREDRAW;
  wc.cbClsExtra    = 0;
  wc.cbWndExtra    = 0;
  wc.lpszClassName = L"Window";
  wc.hInstance     = hInstance;
  wc.hbrBackground = GetSysColorBrush(COLOR_3DFACE);
  wc.lpszMenuName  = NULL;
  wc.lpfnWndProc   = WndProc;
  wc.hCursor       = LoadCursor(NULL, IDC_ARROW);
  wc.hIcon         = LoadIcon(NULL, IDI_APPLICATION);
  
  RegisterClassW(&amp;wc);
  hwnd = CreateWindowW( wc.lpszClassName, L"Window",
                WS_OVERLAPPEDWINDOW | WS_VISIBLE,
                100, 100, 350, 250, NULL, NULL, hInstance, NULL);  

  ShowWindow(hwnd, nCmdShow);
  UpdateWindow(hwnd);

  while( GetMessage(&amp;msg, NULL, 0, 0)) {
    DispatchMessage(&amp;msg);
  }

  return (int) msg.wParam;
}

LRESULT CALLBACK WndProc(HWND hwnd, UINT msg, 
    WPARAM wParam, LPARAM lParam)
{
  switch(msg)  
  {
    case WM_DESTROY:
      PostQuitMessage(0);
      return 0;      
  }

  return DefWindowProcW(hwnd, msg, wParam, lParam);
}
</pre>

<p>
Follows a step by step explanation of the code example. 
</p>

<pre class="explanation">
#include &lt;windows.h&gt;
</pre>

<p>
This is a header file for the C programming language. 
It contains all function declarations in the API, all common macros 
and all the data types. The Win32 API is added to the C programming 
project by linking the necessary libraries, kernel32.lib, user32.lib,
gdi32.lib and by including the &lt;windows.h&gt; header file.
</p>

<pre class="explanation">
wc.style = CS_HREDRAW | CS_VREDRAW;
</pre>

<p>
We set the window style here. The <code>CS_HREDRAW</code> and 
<code>CS_VREDRAW</code> flags mean that whenever there is a movement or 
size adjustement of the height or width of the window, the entire window 
is redrawn.
</p>

<pre class="explanation">
wc.cbClsExtra    = 0;
wc.cbWndExtra    = 0;
</pre>

<p>
In our example, we do not use the additional bytes. So we set 
the members to zero.
</p>

<pre class="explanation">
wc.lpszClassName = L"Window";
</pre>

<p>
Window is a class name for this particular window type. We will 
use this class name when creating the window. The L character precedes 
wide strings.
</p>

<pre class="explanation">
wc.hInstance = hInstance;
</pre>

<p>
We set the instance of our program.
</p>

<pre class="explanation">
wc.hbrBackground = GetSysColorBrush(COLOR_3DFACE);
</pre>

<p>
Here we set the background brush. It is the colour that is used to 
paint the client area of the window.
</p>

<pre class="explanation">
wc.lpszMenuName  = NULL;
</pre>

<p>
In our example, we do not create a menu. 
</p>

<pre class="explanation">
wc.lpfnWndProc = WndProc;
</pre>

<p>
We provide the window procedure for the window class.
</p>

<pre class="explanation">
wc.hCursor = LoadCursor(NULL, IDC_ARROW);
wc.hIcon   = LoadIcon(NULL, IDI_APPLICATION);
</pre>

<p>
We set the cursor and the icon for our application. We load them 
from system resources.
</p>

<pre class="explanation">
RegisterClassW(&amp;wc);
</pre>

<p>
We register the window class with the system. 
</p>

<pre class="explanation">
ShowWindow(hwnd, nCmdShow);
UpdateWindow(hwnd);
</pre>

<p>
These two lines show the window on the screen. The <code>nCmdShow</code> 
specifies, how we display the window on the screen.
</p>

<pre class="explanation">
while( GetMessage(&amp;msg, NULL, 0, 0)) {
  DispatchMessage(&amp;msg);
}
</pre>

<p>
This is the message loop. We receive messages from the message queue using 
the <code>GetMessage()</code> function and dispatch them to the window 
procedure using the <code>DispatchMessage()</code> call.
</p>

<pre class="explanation">
switch(msg)  
{
  case WM_DESTROY:
    PostQuitMessage(0);
    return 0;      
}

return DefWindowProcW(hwnd, msg, wParam, lParam);
</pre>

<p>
In the windows procedure, we react to the <code>WM_DESTROY</code> message. 
The <code>PostQuitMessage()</code> sends the <code>WM_QUIT</code> message to 
the message queue. All other messages are sent to the default processing 
using the <code>DefWindowProcW()</code> function call.
</p>

<img src="/img/gui/winapi/window.png" alt="A window">
<div class="figure">Figure: A window</div>

                                                          
<p>
In this part of the Winapi tutorial, we have created a basic window. 
</p>

<div class="center"> 
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* horizontal */
google_ad_slot = "1734478269";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 
</div> 
<br> 


<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified September 18, 2012  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>
